docs(skills): objectstack-upgrade teaches the stored pass before 18.3 drops the ≤16.x conversions - #28918

domain:skills#1 · huangyiirene · session_01J8VVAnMUWA9rufXzFaEh4J

Contract-review-claim: session_01J8VVAnMUWA9rufXzFaEh4J · head 3bf0627 · 2026-11-02T04:18Z

The seat review runs at CONTRACT_REVIEW_TIER in an isolated subagent (the seat session is not at that tier).

domain:skills#1 · huangyiirene · session_01J8VVAnMUWA9rufXzFaEh4J

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3bf0627876043d1a60a6ae31d9af0a35dfa66faa
Local-runs: none
Scope: skills/objectstack-upgrade/SKILL.md, skills/objectstack-upgrade/evals/protocol-major-upgrade.json, skills/objectstack-upgrade/references/examples-upgrade.md + .changeset/25767-retire-16x-retirement-kits.md, packages/spec/src/conversions/stored.ts, packages/spec/src/conversions/apply.ts, packages/spec/src/conversions/registry.ts (retiredAfter census at tags @objectstack/spec@18.1.0, @objectstack/spec@18.2.0 and main b15b634), packages/metadata-protocol/src/stored-migration.ts, packages/metadata-protocol/src/protocol.ts (migrateStoredMetadata), packages/metadata-protocol/src/protocol-stored-item-conversion.ts, packages/metadata/src/loaders/database-loader.ts, packages/objectql/src/plugin.ts, packages/cli/src/commands/migrate/meta.ts, packages/spec/scripts/build-skill-docs.ts, .changeset/config.json, ui/scripts/check-skill-eval-tokens.mjs. Remainder (.changeset/26303-upgrade-skill-stored-rows-before-18-3.md) is the lane seat's ACCEPT at TIER_DEFAULT.

Reviewer: an isolated subagent at CONTRACT_REVIEW_TIER, adopted by the seat; inputs were the card and all its comments, the PR body, file list and net diff, and the head's check-runs — not the dispatch order or the seat's conclusions.

① Derived judgments

• Public surface / accept-set: none moves — right. Prose and one eval fixture in the published @objectstack/skills bundle, plus a changeset. No schema, authorable key, CLI flag, exit code or runtime seam changes; Metadata-protocol: none and Clause-②: no are right.
• "Rehydration replays every conversion the release still carries, including entries retired from the load path" — right. applyConversionsToStoredItem (packages/spec/src/conversions/stored.ts) pins includeRetired: true over ALL_CONVERSIONS; the engines.protocol window belongs to the artifact-ingestion door, not the stored seam. Same code at 18.1.0, 18.2.0 and main.
• "18.3 drops those retired at or below 16.x" — right on the tree. retiredAfter census in packages/spec/src: tag 18.2.0 → 5 at 15.x, 45 at 16.x; tag 18.1.0 → the same 50; main → 0 at ≤16.x. packages/spec/package.json reads 18.2.0 and .changeset/25767-retire-16x-retirement-kits.md is minor with no pending major, so the drop ships as 18.3.
• "On 18.2 the stored pass canonicalizes a ≤16.x row" — right. At 18.2.0 migrateStoredMetadata and both read seams call applyConversionsToStoredItem without excludeConversionIds (only flow seams exclude), so every surviving ≤16.x conversion fires on a non-flow row.
• "--stored takes no --from" — right. meta.ts declares from exclusive: ['stored']; run() branches into runStored before the --from requirement.
• Exit codes — right. runStored exits 1 iff !storedMigrationClean(report) (pending === 0 && failed === 0); --apply without --yes in a non-TTY emits confirmation_required, exit 1.
• Eval 5's commands exist as written — right. All three are in the command's own examples and in SKILL.md's block.
• No generated artifact owed — right. gen:skill-docs reads frontmatter only, unchanged; the check:skill-docs, check:skill-refs, check:skill-examples and token-ratchet lanes are green on the head.
• Card acceptance met — right. Before/after counts in the PR body (package 647 → 655, budget +15); eval 4 amended, eval 5 added; nothing removed beyond the stale sentences of the one claim.

② Semver level

'@objectstack/skills': patch matches a corrected teaching with no API, schema or command change; the package is in the fixed group of .changeset/config.json. Changeset and PR body both carry Clause-②: no and Metadata-protocol: none, consistent with the diff. Check Changeset green. Correct.

③ Boundary flags

Dev report 6568912467: open_questions: [].

1. Scope widened to § 3.6 and references/examples-upgrade.md — accepted: same stale claim, inside the declared surface.
2. Shared checkout detached for the worktree — process note, no contract matter.
3. check:dual-build-cjs-loads NOT MEASURED locally — no code path in the diff; CI Build Core success carries it.
4. No assignee/reviewer/subscription — the seat's hand-off.
5. Out-of-scope finding, carrier: none: the headers of packages/spec/src/conversions/stored.ts ("keeps every conversion forever") and packages/metadata-protocol/src/stored-migration.ts ("served canonical forever"), and AGENTS.md Prime Directive Add comprehensive test suite for Zod schema validation #12 ("replays the full conversion chain — retired entries included") are false for ≤16.x shapes on main. Escalated to the seat, not answered here: a governed rule agents act on now says something wrong; owed a card for its owner. Not this PR's surface, not a blocker.

premise_still_valid: true — independently re-verified (counts above).

④ Design judgment

skills/objectstack-upgrade/SKILL.md — holds. Against the card's scenario (16-era sys_metadata rows moving onto the release that drops the ≤16.x kits) and main: the stored seam is not windowed; only flow seams exclude ids and flows canonicalize under the same full-chain policy; "18.3" matches the tree. Should-fix: "a row still in such a shape is no longer rewritten" is true but understates — on 18.3 migrateStoredMetadata records such a row canonical (no notice, no todo), so os migrate meta --stored --json exits 0 on exactly the row the skill warns about. § 3.6's "get 0 before you move" is right because it binds to the release being left, but the skill never says an 18.3 exit 0 is not evidence. One clause; SKILL.md has 22 tokens of headroom.

skills/objectstack-upgrade/evals/protocol-major-upgrade.json — holds. Eval 4 keeps every must_contain token and states a true sequence. Eval 5's scenario is the changeset's trap; 18.1.0 carries the 50 conversions; all three commands exist with the stated exit semantics; each must_contain token appears in SKILL.md at the head (checked by reading: the repo's eval-token gate covers ui/skills/objectui only).

skills/objectstack-upgrade/references/examples-upgrade.md — holds. The optional checklist item becomes a pending per-deployment gate under "Pending, per deployment", consistent with § Stored rows and § 3.6; within its 1197 ceiling.

No must-fix. One should-fix (SKILL.md, the 18.3 exit-0 clause) and one escalation (the Prime Directive #12 / module-header drift).

Check-runs still in_progress at review time: Test Core (1/8), Test Core (2/8), Type Check · consumer gates, Type Check · debt ledger; the seat reads them before any hand-off.

Implemented-by: claude/project-thread-gszymj
Reviewed-by: session_01J8VVAnMUWA9rufXzFaEh4J

VERDICT: PASS

Generated by Claude Code

domain:skills#1 · huangyiirene · session_01J8VVAnMUWA9rufXzFaEh4J

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 43d397d498d05ffaa719726fd263bb8f14bf4206
Local-runs: none
Scope: skills/objectstack-upgrade/SKILL.md, skills/objectstack-upgrade/evals/protocol-major-upgrade.json, skills/objectstack-upgrade/references/examples-upgrade.md + .changeset/25767-retire-16x-retirement-kits.md, packages/spec/src/conversions/stored.ts, packages/spec/src/conversions/apply.ts, packages/spec/src/conversions/registry.ts, packages/metadata-protocol/src/stored-migration.ts, packages/metadata-protocol/src/protocol.ts (migrateStoredMetadata), packages/metadata-protocol/src/protocol-stored-item-conversion.ts, packages/metadata/src/loaders/database-loader.ts, packages/objectql/src/plugin.ts, packages/cli/src/commands/migrate/meta.ts, packages/spec/scripts/build-skill-docs.ts, .changeset/config.json, ui/scripts/check-skill-eval-tokens.mjs, scripts/check-skills-token-ratchet.mjs. Remainder (.changeset/26303-upgrade-skill-stored-rows-before-18-3.md, unchanged in this delta) is the lane seat's ACCEPT at TIER_DEFAULT.

Delta record over record 6569077178 on 3bf0627876 (PASS, one should-fix), by the same reviewer (isolated subagent at CONTRACT_REVIEW_TIER, adopted by the seat). The new head is one commit on top, pushed without force; the delta 3bf0627876..43d397d498 touches SKILL.md § 3.6 (one paragraph) and eval 5's expected_output (one clause). references/examples-upgrade.md, the changeset and every cited code path are byte-identical; every judgment of 6569077178 not about § 3.6 or eval 5 carries over. Inputs: that diff, the dev's delta report 6569140493 (input, not conclusions), the head's check-runs.

① Derived judgments

• Accept-set / public surface: nothing moves — right. Prose and one eval sentence; Clause-②: no / Metadata-protocol: none stay right.
• New § 3.6 sentence ("valid only on the release you are leaving: one that dropped a row's conversions no longer recognises it and answers 0") — right on main. migrateStoredMetadata sets changed from the notices of convertStoredItemDetailed → applyConversionsToStoredItem over the installed conversions; no notice and no todo records the row canonical; storedMigrationClean is pending === 0 && failed === 0; runStored exits 1 only when not clean. With no ≤16.x retiredAfter on main, a ≤16.x-shaped non-flow row → canonical → exit 0.
• Eval 5's appended clause — right, by the same reading; assertions unchanged and every must_contain token still in SKILL.md.
• The imperative is not lost: § Stored rows still says "⛔ Run the stored pass before you move (on 18.2 or earlier for such a row)", and eval 5 still requires exit 0 on 18.1 before the bump.
• Token ratchet, read off the blob: SKILL.md 6185 priced of ceiling 6188 (headroom 3); package 647 → 656 (+9 of +15). No ceiling moved.

② Semver level

Unchanged: '@objectstack/skills': patch, Clause-②: no, Metadata-protocol: none. Correct.

③ Boundary flags

Delta report 6569140493: open_questions: [], out_of_scope_findings: [].

1. PR body not edited, so its line/token table and cited head are stale — answered: the seat's ACCEPT carries the corrected readings (confirmed above).
2. premise_still_valid: true — cited code byte-identical; holds.
3. The escalation of 6569077178 (AGENTS.md Prime Directive Add comprehensive test suite for Zod schema validation #12 and the two module headers) is filed as AGENTS.md Prime Directive #12 and two stored-conversion headers still say every conversion replays forever; 18.3 drops the ≤16.x ones #28924; not this PR's surface.

④ Design judgment

SKILL.md — holds; the prior should-fix is landed. Tried to break it: an 18.3 pass cannot flag such a row through onTodo/refused shapes (those cover two protocol-18 shapes only); the sentence speaks only to what the stored pass answers, which is 0 whichever container the key sat in; removing "so get 0 before you move" does not weaken the instruction (see ①).
evals/protocol-major-upgrade.json — holds. No finding.
references/examples-upgrade.md — unchanged; prior judgment carries over.

No must-fix. No new should-fix.

Check-runs at review time: several required lanes still in_progress; the seat reads them green before any hand-off.

Implemented-by: claude/project-thread-gszymj
Reviewed-by: session_01J8VVAnMUWA9rufXzFaEh4J

VERDICT: PASS

Generated by Claude Code

domain:skills#1 · huangyiirene · session_01J8VVAnMUWA9rufXzFaEh4J

维护者速读

• 改了什么: objectstack-upgrade 技能不再说「16 时代存下的 sys_metadata 行读取时会被永远自动改写」;改为:18.3 去掉 ≤16.x 的转换后这类行不再被改写,要在 18.2 或更早版本上先跑 os migrate meta --stored --apply --yes,并说明在 18.3 上 --stored --json 退出 0 不能证明这类行已迁移。eval 4 改句,新增 eval 5 问「18.1 直升 18.3」。
• 为什么改: 去掉 ≤16.x 转换的 feat(spec)!: retirement kits whose conversion retired at or below 16.x age out; the strict unknown-key refusal names the protocol upgrade guide #26599 已合入 main、随 18.3 发布;照旧技能做的客户升到 18.3 后,存量行会停在旧形状,而 18.3 上的存量迁移也救不回来、还会报「全部正常」。
• 风险与回滚: 只改对外技能文本、报告模板一行与 eval,不动代码、schema、命令;两份受 token 棘轮约束的文件都在上限内(SKILL.md 6185/6188),上限未动;回滚即 revert。
• 先看: ① skills/objectstack-upgrade/SKILL.md "Stored rows" 一节与 § 3.6 末段;② evals/protocol-major-upgrade.json 的 eval 4 与新 eval 5;③ references/examples-upgrade.md 报告模板的存量迁移一行。
• 两分钟验证: node scripts/check-skills-token-ratchet.mjs && pnpm --filter @objectstack/spec check:skill-docs 均绿;grep -n "rehydrates in its protocol-17" skills/objectstack-upgrade/SKILL.md 零命中。
• 需要你做的: 审批本 PR(skills/** 是 Tier H)。达档契约复核 PASS 在案:评论 6569183763,Head-sha: 43d397d498d05ffaa719726fd263bb8f14bf4206。批准后由本席落地。18.3 请在本 PR 合入后再发(Version Packages PR chore: version packages #26517 已带上 feat(spec)!: retirement kits whose conversion retired at or below 16.x age out; the strict unknown-key refusal names the protocol upgrade guide #26599)。
• 席位意见: ACCEPT。教学与 main 上的代码逐条对得上(复核读了 applyConversionsToStoredItem、migrateStoredMetadata、meta.ts 的退出码);补丁轮补上了「18.3 上退出 0 不算数」这个陷阱。

席位核对 — ACCEPT · domain:skills#1 · head 43d397d498d05ffaa719726fd263bb8f14bf4206

1. 形态: draft → main,正文首段 Fixes #26303,无他卡关键词;作者 objectstack-fleet[bot](中继)。
2. 前提实测: 18.2.0 标签上 retiredAfter ≤16.x 的转换 50 个,main 上 0 个;packages/spec/package.json 18.2.0,changeset 25767-retire-16x-retirement-kits 为 minor 且未发布(复核记录 6569077178 / 6569183763)。
3. 门禁 check-runs(钉 head 43d397d4): success 28 / skipped 13 / 无红无在跑;Lint & Repo Gates、Type Check · workspace、Check Changeset success。check-governed-merges --pr 28918:Tier H(skills/** ×3),+35/−14。
4. 接受的偏差: 范围扩到 § 3.6 末句与报告模板一行(同一过时说法,在申报面内);补丁轮按复核 should-fix 补「18.3 上 exit 0 不算数」。PR 正文读数已过时,以此为准: SKILL.md 483 → 482(−1)、tokens 6176 → 6190(棘轮计价 6185,上限 6188);eval tokens 1033 → 1339;包 647 → 656(+9,预算 +15);全部 SKILL.md 合计 4554 → 4553(−1);正文 Tests / Acceptance notes / Verification 所引 head 应为 43d397d498。
5. 范围外去向: dev 观察到的 AGENTS.md Prime Directive Add comprehensive test suite for Zod schema validation #12 与两处模块头注释漂移 → filed AGENTS.md Prime Directive #12 and two stored-conversion headers still say every conversion replays forever; 18.3 drops the ≤16.x ones #28924。Skills-docs: 不适用(Metadata-protocol: none)。changeset .changeset/26303-upgrade-skill-stored-rows-before-18-3.md 逐句对照 diff 核过(Before / Now 两条与 SKILL.md、eval、模板改动一致)。
6. 落地条款: Tier H。等 GOVERNED_APPROVERS 授权批准;批准后本席过落地前检、清 needs-user-decision、pr_ready + automerge_enable。

Generated by Claude Code

domain:skills#1 · huangyiirene · session_01J8VVAnMUWA9rufXzFaEh4J

Regen-provenance: 6569183763 · 43d397d → 4e175a6 · git diff --stat 43d397d 4e175a6 -- ':!.changeset/' → (empty)

Head moved on a prose face only. 4e175a6ac4 is one commit on 43d397d498 touching .changeset/26303-upgrade-skill-stored-rows-before-18-3.md alone (1 line), so the contract-review record 6569183763 carries to the new head. Seat record 6569353621 (ACCEPT) carries too, with this correction to its item 5: the changeset sentence the seat checked against the diff is now the Now bullet's "§ 3.6 says the os migrate meta --stored --json exit 0 counts only on the release being left, because one that dropped a row's conversions answers 0 without recognising the row" — it matches § 3.6 at the head; the earlier "§ 3.6 says to get exit 0 … before the move" no longer matched after the patch round and is gone. The hand-off to the approvers waits for check-runs on 4e175a6ac4.

Generated by Claude Code